package de.preamp.clients.java.player;

import java.io.IOException;

import javax.sound.sampled.LineUnavailableException;
import javax.sound.sampled.UnsupportedAudioFileException;

/**
 * This Interface provides the operations that can be applied to the actual
 * playing component from the UI.
 * 
 * @author André Stannek
 * @since 2010-08-18
 * @version 2010-08-22
 */
public interface PlayerControls
{

    /**
     * If nothing is played this operation gets the current track from the
     * active playlist and starts to play it. if already playing it provides the
     * classical pause/play function. It should be called when the
     * "play/pause-button" is pressed.
     * 
     * @throws LineUnavailableException
     *             if a matching line is not available due to resource
     *             restrictions
     * @throws IOException
     *             on I/O Error
     * @throws UnsupportedAudioFileException
     *             if the stream does not point to valid audio file data
     *             recognized by the system
     * @throws PreampPlayerException
     *             if playback thread was interrupted
     */
    void playPauseToggle() throws UnsupportedAudioFileException, IOException,
	    LineUnavailableException, PreampPlayerException;

    /**
     * Sets the playlist marker to the track previous to the current and plays
     * it. It should be called when the "previous-button" is pressed.
     * 
     * @throws LineUnavailableException
     *             if a matching line is not available due to resource
     *             restrictions
     * @throws IOException
     *             on I/O Error
     * @throws UnsupportedAudioFileException
     *             if the stream does not point to valid audio file data
     *             recognized by the system
     * @throws PreampPlayerException
     *             if playback thread was interrupted
     */
    void previous() throws UnsupportedAudioFileException, IOException,
	    LineUnavailableException, PreampPlayerException;

    /**
     * Sets the playlist marker to the track next to the current and plays it.
     * It should be called when the "next-button" is pressed.
     * 
     * @throws LineUnavailableException
     *             if a matching line is not available due to resource
     *             restrictions
     * @throws IOException
     *             on I/O Error
     * @throws UnsupportedAudioFileException
     *             if the stream does not point to valid audio file data
     *             recognized by the system
     * @throws PreampPlayerException
     *             if playback thread was interrupted
     */
    void next() throws UnsupportedAudioFileException, IOException,
	    LineUnavailableException, PreampPlayerException;;

    /**
     * Stops the playback of the current track. It should be called when the
     * "stop-button" is pressed.
     */
    void stop();

    /**
     * @param length
     *            the length of the part to skip in milliseconds @throws
     * @throws LineUnavailableException
     *             if a matching line is not available due to resource
     *             restrictions
     */
    void seek(final Integer length) throws LineUnavailableException;

    /**
     * Adds a PlaybackListener to this Manager.
     * 
     * @param listener
     *            the listener to add
     */
    void addPlaybackListener(final PlaybackListener listener);

    /**
     * Removes a PlaybackListener from this Manager.
     * 
     * @param listener
     *            the listener to remove
     */
    void removePlaybackListener(final PlaybackListener listener);

}
